The Atari Compendium/The Atari Compendium (Toad Computers) (1994).iso/files/prgtools/programm.ing/progem.lzh/wind17.prf

Text File | 1987-06-23 | 22.5 KB | 474 lines

.!****************************************************************************
.!
.! ANTIC PUBLISHING INC., COPYRIGHT 1985.  REPRINTED BY PERMISSION.
.!
.! ** Professional GEM ** by Tim Oren
.!
.! Proff File by ST enthusiasts at
.! Case Western Reserve University
.! Cleveland, Ohio
.! uucp : decvax!cwruecmp!bammi
.! csnet: bammi@case
.! arpa : bammi%case@csnet-relay
.! compuserve: 71515,155
.!
.!****************************************************************************
.!
.!
.!****************************************************************************
.!
.!            Begin Part XVII
.!
.!****************************************************************************
.!
.PART XVII PC/ST Resource Converter
.PP
This the seventeenth installment of ST PRO GEM, the
first to feature a complete GEM application.  The program
converts resource files between the ST (68000) and IBM PC
(Intel) formats used by the respective versions of GEM and
the Resource Construction Set.
.PP
The Resource Converter will, for the most part, be of
direct use only if you are doing cross-development of GEM
software on these two systems.  In this case, you will want
to read this entire article, starting with the "What It Does"
heading.  You may also be interested in an article on PC/ST
conversion written by Mark Skapinker of Batteries Included,
which appears in the Fall issue of START magazine (available
September 1986).
.PP
If you are not doing cross machine development, you can
still get something out of this column.  Reading the program
code and following the discussion, you will find practical
examples of using GEM dialogs and following the internal
structure of a resource file.  Finally, there is a good deal
of standard code for GEM initialization, AES utility
functions, and GEMDOS file handling which you can extract for
your own uses.  If you fall in this category, skip the first
parts of the column, and resume reading at the "How it Works"
heading.
.PP
     The download for this column is a set of source and
binary files located on DL3 of the ATARI16 SIG, PCS-58.  The
files and their contents are:

     RCMAIN.C   -  Download and rename to RSCVMAIN.C
                    This is the C source for main routine
     RCFILE.C   -  Download and rename to  RSCVFILE.C
                    This is the C source of GEMDOS utilities
     RCLIB.C    -  Download and rename to RSCVLIB.C
                    C source of AES utility functions
     RSCONV.PRG -  Linked binary of converter
     RSCONV.RSC -  Binary resource image (ST format)
     RSCONV.DFN -  Symbol file for resource (ST format for
                    RCS 2.0)
     RSCONV.H   -  Object/tree name file for resource
     RLINK.SH   -  Download and rename to RSCVLINK.SH
                    C-shell script for linking RSCONV
     SYLINK.SH  -  Download and rename to SYMLINK.SH
                    Another script, used by RSCVLINK.SH
.PP
The final two files will be of use only if you are using Dave
Beckemeyer's Micro C-Shell environment.  If not, you can
simply translate them to .BAT and/or .INP form for use with
the Atari batch program and linker.
.SH WHAT IT DOES
A converter program is necessary because of the
differing order of storage on the 68000 and Intel chips:  the
order of significance of bytes within words is reversed, as
well as the order of words within long (32-bit) quantities.
Attempting to load an unconverted resource on a GEM system
with the other architecture will result in a crash, because
all of the pointer and integer fields will be incorrect.
.PP
In addition, the format of symbol definition (DEF) files
differs between the PC and ST implementations of the RCS in
its first version.  In the latest version from DRI, the
formats do correspond, and the files now carry an extent name
of DFN.  However, the byte swapping problem must be corrected
in either format for the symbols to be correctly loaded.
     As final touch, the converter also checks to be sure
that a resource being loaded from the PC has its bit images
synchronized to an even byte boundary.  If this is not
corrected, the ST will suffer a bus error when attempted to
address the images with a word type operation, which will
certainly happen in either the RCS or the application itself
on the target system.
.SH OPERATION
When the Resource Converter loads, it presents an
initial dialog box.  (The converter does not use the menu
bar.) The dialog has action buttons at the bottom labelled
"Help", "Convert" and "Quit".  Clicking the Help button will
obtain a screen which summarizes these operating
instructions.  The Quit button terminates the program.
Clicking Convert initiates the program's action, according to
the options you have set in the rest of the dialog.
.PP
The top two buttons in the dialog establish the
direction of the conversion.  If you have built a resource on
the PC and want to move it to the ST, click Intel->68000.  If
you are moving the file from the ST to the PC, click
68000->Intel.
.PP
The next two lines in the dialog establish the file
extent names which will be used for the conversion.  The
input extent names are always on the left, no matter which
conversion mode you selected above.  By default, they are RSC
and DEF.  The output extents, on the right, are RS2 and DF2
by default.  The RSC/RS2 file extents are used for the
resource, and DEF/DF2 extents are for the symbol file.  Be
careful that the input files you use are actually of the type
(Intel or 68000) which you specified.  If you get it
backwards, the ST will most likely crash, though the input
files will not be harmed.
.PP
The three buttons below the file extents determine the
format of the input and output symbol files.  If you click on
DEF, the Resource Converter will assume that the input and
output symbol files are in the old (that is, version 1.1)
format used by the RCS.  If you click on DFN, the program
expects the new (version 2.0) symbol format.  If the input
symbol file extent is still set to "DEF", clicking this
button will also change it appropriately.  (Note that the DEF
and DFN formats are in fact IDENTICAL on the PC ONLY.  To
"change formats" ON THE PC, you need only change the file's
extent name, for example, rename FOOBAZ.DEF to FOOBAZ.DFN.
On the ST, there is a real difference,and you must use the
DRI DEF2DFN.PRG utility to go from old to new.)
.PP
The last button option is (OFF).  Clicking this button
disables the symbol file conversion.  You may use this option
to keep better control over versions of your resource.  By
establishing the main version on either the PC or ST, and
converting only the resource file, not the symbols, you can
ensure that no one will use the RCS on the destination
machine to create a version which is different from the
source.
.PP
When the Convert button is clicked to begin execution,
the standard Item Selector is displayed.  Use it to find and
pick the input resource file which you want to convert.  The
Converter will use its main filename, substituting the
various extents, to find the input definition file, and
produce the output file names.  If the definition file cannot
be found in the same directory under the generated name, you
will be presented with an alert, asking you to abort the
conversion, continue without the symbol file, or specify a
new name and/or directory for the file.  If the output names
coincide with existing files, they will be overwritten.
.PP
While the conversion operation is occurring, a progress
indicator box will be displayed on the screen, with text
messages indicating the current phase of the operation.  When
the conversion is complete, you are returned to the initial
dialog, where you may quit or perform another conversion.
.PP
One last note on conversion, with a caution:  it is
possible to move files between Intel and 68000 even if you
have two different versions of the Resource Construction Set,
for instance, Version 2.0 on the PC and Version 1.1 on the
ST.  In this situation, you can take advantage of the
identity between symbol file formats on the PC.  Make a copy
of the PC symbol file into another file with the DEF extent,
and run the converter.  The output should load on the ST
version correctly.  However, if you move symbols between
different RCS versions, you MUST NOT use the "free strings"
and "free images" features of version 2 and then move the
symbols to version 1.  Doing so may result in spurious
assignment of the "free" symbols to trees and objects, and
you will (of course) not be able to edit the free images
and/or strings in the resource.
.SH HOW IT WORKS
For the ST-only developers now rejoining the discussion,
I will now take a look at the standard GEM initialization
code and the special dialog handling techniques which I have
used in the Converter.  Then we'll look at the guts of the
code, which threads through the resource to do the actual
conversion.  For those interested in the supporting code
libraries, the GEMDOS interface utilities in RSCVFILE.C were
described in column number 15.  The progress indicator
functions of RCSLIB.C were detailed in column 16, and
map_tree() and standard dialog handling techniques were
discussed in columns three through five.
.PP
There are a number of useful facts in rscv_init(), the
initialization code.  First, notice that the result of
appl_init is NOT assigned directly to gl_apid.  Due to a bug
in the appl_init binding the application ID is not returned
as the function value.  Instead it is returned to the global
variable gl_apid.  This bug wouldn't cause direct problems in
the resource converter, but it will in any program which uses
the ID when sending messages to its own pipe.
.PP
Next, an alert string to be displayed if the resource is
not found has been explicitly included, to avoid a "Catch-22"
situation.  You can easily create such a string by building
the alert in the RCS, using the C output option, and
extracting the string from the resulting file.
.PP
Rscv_init() then sets up its VDI handle, by getting the
physical workstation handle from graf_handle, and passing it
to v_opnvwk (open virtual workstation), which returns the
virtual workstation handle for use in VDI calls.  V_opnvwk
also returns the dimensions of the screen, which are copied
to GRECT scrn_area, and the number of color planes, which is
used to set up an MFDB for the screen:  scrn_mfdb.
.PP
The wind_get call for the working area of the DESK
window (number zero) results in the usable GRECT of the
screen.  This is different from scrn_area, because the menu
bar's rectangle is reserved for the system.
.PP
You may want to take particular notice of the vst_height
call, which reloads the character dimension variables.  The
values returned earlier by graf_handle are ALWAYS for the
monochrome (high resolution) system font, and they are not
appropriate for the low and medium resolution modes of the
ST.  Performing the vst_height call AFTER opening the virtual
workstation will get the correct dimensions.
.PP
Some of the environment variables which are set up by
rscv_init(), are not actually used in the resource converter.
I have included them because they are part of my "generic"
initialization procedures.
.PP
Finally, rscv_init() uses Malloc to reserve most of
memory as a working buffer for the resource conversion.
Notice that 4K are left free.  You must leave at least 2K,
and preferably a safety factor, or the AES will be unable to
allocate memory for the file selector dialog, and your
application will hang when calling fsel_input.  By the way,
an open virtual workstation uses about 8K, so you should do
your Mallocs after the workstation call.
.PP
We now turn our attention to do_mode(), which handles
the main dialog of the converter.  After getting the root
address of the dialog tree, the states of global variables
conv_def and new_dfn are used to set up the radio button
array for symbol file conversion.  Native_in is used to set
up the conversion type radio buttons.  The last
initialization step is to use the set_text() utility to link
the file extent strings into the appropriate editable
objects.  Notice that this version of set_text() allows the
string length to be explicitly supplied.  For an editable
text field object (G_FTEXT or G_FBOXTEXT), the length must be
one greater than the number of blanks in the editing
template.
.PP
Since there are TOUCHEXIT objects in the dialog, we
cannot use the standard hndl_dial() routine.  Instead, the
form setup and draw calls are coded inline.  The actual
form_do call is placed inside a loop.  If the object returned
is not one of the TOUCHEXIT objects, the loop is terminated.
.PP
The two objects DEFYES and DFNYES, which select the old
and new symbol file formats, respectively, have been made
TOUCHEXIT.  If either is clicked, the radio button processing
is done by the AES, but then control is returned from
form_do.  Do_mode() then tests the current input symbol file
extent.  If it is "DEF" and we are switching from old to new
mode, the extent is changed to "DFN".  When switching from
new to old mode, the reverse check is made.  In either case,
the disp_obj() utility is used to force an immediate redraw
before returning to form_do for further user input.
.PP
When the loop terminates, do_mode() cleans up the screen
with form_dial, and uses the selected() utility to retrieve
the status of the radio button arrays and update the global
variables.  Finally, map_tree() is used to apply the
deselection utility to all objects in the tree, leaving it
clean for the next invocation of do_mode().
.SH THE BELLY OF THE BEAST
The routine dconv() contains the code for actually
converting the resource.  About half of do_conv() is devoted
to accessing disk files, and correctly handling error
conditions which might arise.  The error recovery could
perhaps be handled more concisely with artifices like
"setjmp", but I have left it in-line for the sake of clarity.
.PP
Do_conv() also uses a collection of routines whose names
begin with "swap_" Swap_bytes() and swap_words() are the
workhorse routines.  They simply run through a given area of
memory, reversing every pair of bytes or words, respectively.
(Remember that the word swapper will only work on even byte
boundaries, or a bus fault will occur.) The other swap
routines do the fix up for one type of resource structure
each.  I'll take apart a couple in detail, so that you can
see the similarities in the others.
.PP
Now let's follow the do_conv() code.  The first item of
business is to use the get_file() utility, followed by
open_file(), to find and open the input resource file.
Again, you can see column 15 for a a discussion of these
routines, which will handle DOS errors if they occur.
.PP
The Boolean conv_def is true if we need to open a
symbols file.  If everything goes right, just substituting a
new extent name (from variable old_def), and doing the file
open will get the file.  If things foul up, do_conv() has to
recover gracefully.  So, it puts up the three button alert
NODEF.  The third button is an abort option;  if it's picked
we punt, closing the one open file and returning to the main
dialog.  Button one allows a continuation without the
definition file (conv_def is forced FALSE so the user won't
make the same mistake twice).  Button two says try again, so
get_file() is called to pick another file, and the whole
process repeats.
.PP
Once the input file(s) are open, the operation will run
to completion, assuming no disk errors.  The mouse form is
switched to an hour glass, and a progress indicator box is
initialized on the screen.
.PP
The first action is to bring in the resource header
only.  If the resource is not native, that is, is not in
68000 format, its bytes must be swapped before using any of
the counts and offsets.  Note:  if you've never dissected a
resource before, this would be a good time take a look at the
header format given in "gemdefs.h" in the Developer's Kit,
and the resource structure definitions in "obdefs.h".
.PP
After the swap, if necessary, the resource size field
can be used.  Before reading the rest of the resource, the
size must be compared against the size of the buffer
allocated during initialization.  If there isn't enough room,
the NOMEM alert is displayed and control returns to the main
dialog.  (Since the biggest resource is 64K, and the
Converter is rather small, this shouldn't ever happen.  But,
some people load up lots of desk accessories, so best to be
prepared.)
.PP
After completing the resource input, an (admittedly
kludgy) patch is made for the odd-byte-images problem.  If
the image offset pointer is odd, there will be problems on
the ST.  The fix made here relies on two facts.  First, all
images are an even number of bytes in size.  Second, the old
version of RCS DOES do an even byte synchronization AFTER
writing the images.  Therefore, if the images start on an odd
byte, they will end on an even byte, and have one unused
odd-addressed byte immediately following.  The fixup strategy
is to move all of the images up one byte, patch the offset in
the header accordingly, and leave the img_odd flag set so
that the bit image swap routine will also increment pointers
in the BITBLK and ICONBLKs which use the images.
.PP
If the resource being converted is native, we can do the
image fixup immediately.  If not, all of the other swaps have
to take first, because the long pointers in the BITBLKs and
ICONBLKs are in the wrong order.  (We don't have to swap
string data;  it's always stored in ascending order.)
.PP
Do_conv() calls subroutines to swap the tree index,
objects, TEDINFOs, ICONBLKs, BITBLKs, and free string and
images, in that order.  We'll look at their actual code
later.  When this is finished, one of two cleanup actions is
needed.  If the resource WAS native, everything is now
swapped except the header, which is finally reversed.  If it
used to be foreign (Intel), the pointers are now in proper
68000 order, so swap_images() can be called successfully.
.PP
Now it's time to write the converted resource, taking
care that no error results.  If no symbol file conversion is
needed, do_conv() is done.  The files are closed, the
progress indicator completed, and control returns to
rscv_run, which will set the cursor back to the arrow.
Otherwise, it's time to handle the symbols file.
.PP
The first two bytes in the definition file are always
the symbol count.  They are read into nsym, and a scratch
copy is made in reply, and swapped.  Just which version is
written to the output file depends on whether it is a DFN or
DEF file.  The new (DFN) format keeps a similar word order on
both the ST and PC.  For these files, the following code
amounts to a verbatim copy.
.PP
Nsym is now used as the control variable of a loop which
reads, converts, and writes one symbol entry on each
iteration.  In the old (DEF) file format, there was an extra
word in the value field of each symbol's entry on the ST.
Going from PC to ST, two padding zero bytes are added.  Going
the other way, they are read and discarded.  For the old
format, both the significant word of this field, as well as
the following word field (the type) are swapped.  The ten
symbol bytes are passed through verbatim in both new and old
format.
.PP
After swapping (old format) or simply copying (new
format) of the symbol file is completed, file and progress
box cleanup is done, and control returns.
.SH THE OL' SWITCHEROO
     As promised, let's now go and look at a sampling of
the structure swap routines:  one of the simplest (tree
index), one of medium complexity (objects), and the
worst of the bunch (bit images).
.PP
Swap_trees() is responsible for fixing the tree index.
Its location is found by adding an offset from the header
(rsh_trindex) to the base address of the resource, stored in
head.  (Notice that head was defined as a byte pointer when
the buffer was allocated, so I need to type coerce it to a
resource header pointer before making structure references.)
The number of trees is stored in the rsh_ntree header field.
Each index entry is a long pointer of 32-bits, so the total
size of the index may be found by multiplication.  Finally,
the swapping is done, first bytes within words, then words
within the long pointers.  (The order doesn't matter - work
it out!)
.PP
Swap_objs() takes care of swapping fields inside of
object structures.  It begins similarly to swap_trees(),
computing the base address of the objects from rsh_object,
and taking the count from rsh_nobs.  Since all of the objects
are contiguous in a resource produced by RCS, and all fields
of an object are words or longs, a byte swap is performed on
the entire block at once.  Now there are a couple of tricks.
Notice that "where" in this routine is typed as an object
pointer.  As the number of objects is counted down in the
loop, "where" is incremented.  Because of its type, its
actual pointer value will increase by sizeof(OBJECT) at each
iteration.  Inside the loop, only one long field, the
ob_spec, needs to be word swapped.  When the loop completes,
all object structures are fixed.
.PP
Swap_fstr() and swap_fimg() use code similar to
swap_trees().  The other resource structures, TEDINFOs,
ICONBLKs, and BITBLKs, are transformed by code similar to
swap_objs().  There is one subtlety here.  These structures
would normally be reaching by following an object's ob_spec
pointer.  To finesse a "swap now or later" ordering problem
with the objects, I have instead used the resource header to
find the structure arrays.  You SHOULD NOT use this technique
at run time, for two reasons.  First, if you do any object
patching on the fly, the correspondence between objects and
reference strucutres will be destroyed.  Second, there is no
way to name a non-object structure with the RCS, and
therefore no way to reliably retrieve it with rsrc_gaddr at
execution time.
.PP
Last but not least, swap_images() not only takes care of
switching bit image words, but also fixes image pointers as
necessary if an odd byte problem has been detected.  For
these reasons, swap_images DOES follow pointers from the
ICONBLKs and BITBLKs.  The loop structure of the two sections
of code will be familiar from swap_ibs() and swap_bbs().
Size fields within the structure are used to determine the
length of each image.  If the img_odd flag has been set, the
data pointer must be incremented BEFORE doing the swap, since
the underlying data has already been moved.
.SH PHEW!
This column was deliberately long, in hopes that even
those with no immediate use for this program will gain from
the discussion.  Do to space limits, the feedback is
postponed to episode number 18, which will be another helping
of "interface potpourri".  Ingredients will include the popup
menu code (finally), along with generic code for scrolling
windows, and building your own scroll bars within dialogs.
.!
.!
.!*****************************************************************************
.!*                                          *
.!*                End Part 17                      *
.!*                                          *
.!*****************************************************************************